home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 551-575 / disk_573 / multiplayer / player.doc < prev    next >
Text File  |  1992-05-06  |  41KB  |  946 lines

  1.                 MultiPlayer
  2.                    Version 1.11
  3.                Copyright (C) 1991 Bryan    Ford
  4.                 All    Rights Reserved
  5.  
  6.  
  7.                    Introduction
  8.                    ~~~~~~~~~~~~
  9.  
  10.     MultiPlayer    is a program to    play Amiga music modules, such as
  11. Soundtracker and MED modules. (This program has    no relation to Multi_Player
  12. by Thomas Landspurg which I just recently found    out about.) Before you get
  13. disgusted with Yet Another Module Player, I would encourage you    to read
  14. through    this document, or at least take    MultiPlayer for    a test drive.  You
  15. will find that MultiPlayer has almost all the important    features you've
  16. seen on    other players, plus some you haven't seen before.
  17.  
  18.     One    of the goals of    MultiPlayer is to be as    system-friendly    as
  19. possible.  It multitasks well, it doesn't interfere with high-priority
  20. interrupts such    as serial port interrupts, and it properly allocates audio
  21. channels so that the music doesn't conflict with other programs.  It is
  22. fully functional on Kickstart 2.0 and 1.3 (although the    control    panels look
  23. nicer on 2.0), and isn't prone to "lose" notes on fast processors like
  24. most other players are.
  25.  
  26.     Another goal of MultiPlayer    was to support a very diverse array of
  27. music formats.    MultiPlayer currently supports over fifteen different
  28. common module formats, plus some special ones.    See 'Supported Formats'
  29. near the end of    this document for a list of the    module types MultiPlayer
  30. can play.
  31.  
  32.     The    unregistered version of    MultiPlayer is freely redistributable as
  33. long as    it and its documentation is not    modified in any    way, and the files
  34. listed below are distributed with it.  (See the    end of this file for
  35. details    about registering MultiPlayer.)    You may    not charge more    for
  36. distributing it    than a small fee to cover the disk copying expenses.  The
  37. MultiPlayer version 1.11 distribution must contain the following files:
  38.  
  39.     Player.doc            MultiPlayer documentation (this    file)
  40.     Player                MultiPlayer itself
  41.     Player.info            Icon for MultiPlayer
  42.  
  43.     Programmers/Formats.doc        Specification of GMOD module format
  44.     Programmers/GMOD.i        Include    file to    help with GMOD's
  45.     Programmers/DW_GMOD.asm        Example    GMOD header
  46.     Programmers/DW_Convert.c    Example    program    to write GMOD files
  47.     Programmers/DW_Convert        Executable version of same
  48.     Programmers/LMKFile        SAS/C makefile for DW_Convert
  49.  
  50.     ChipMunch
  51.     ChipMunch/ChipMunch        Useful Utility (for >512K chip RAM)
  52.     ChipMunch/ChipMunch.info    Icon for ChipMunch
  53.     ChipMunch/ChipMunch.doc        Documentation for ChipMunch
  54.     ChipMunch/src/chipmunch.c    SAS/C source for ChipMunch
  55.     ChipMunch/src/makescript    MakeScript for ChipMunch
  56.     ChipMunch/src/sascopts        SAS/C options
  57.  
  58.  
  59.  
  60.                    General Usage
  61.  
  62.     To start MultiPlayer, just type 'player' from the CLI or click on the
  63. icon from the Workbench    and it will present the    ASL or ARP filerequester to
  64. select a module    from, depending    on which version of the    operating system
  65. you are    using.    (If you    are running 1.3, you must have the arp.library
  66. version    39 or higher installed to get the file requester - if you don't,
  67. you won't be able to load modules from the window.) Under 2.0, you can
  68. select multiple    modules    at a time (as many as you want).  Under    1.3, you
  69. will have to select them one at    a time (although you can still build
  70. programs).  If you run MultiPlayer from    the CLI, it automatically detaches
  71. itself,    so there is no need to Run it.    You can    also start modules playing
  72. immediately when MultiPlayer starts up - see the section on 'Startup
  73. Options' for more information on starting MultiPlayer.
  74.  
  75.     While MultiPlayer is running there is normally a small window in the
  76. title bar displaying the name of the module that is currently playing (or
  77. just "MultiPlayer" if nothing is loaded).  You can click the close gadget
  78. to stop    the music and terminate    MultiPlayer.  If you are running Kickstart
  79. 2.0, the MultiPlayer window will have a    zoom gadget near its right end.     If
  80. you click it, you will see a control panel that    allows you to load
  81. different modules and gives access to some of MultiPlayer's more advanced
  82. features.  Since 1.3 doesn't know about zoom gadgets, you can get the
  83. control    panel under 1.3    by pressing the    right mouse button while the
  84. MultiPlayer window is active.
  85.  
  86.     If you have    the xpkmaster.library (a freeware compression "supervisor"
  87. standard by Dominik Mueller, Christian Schneider, and myself) installed    in
  88. your system, MultiPlayer can automatically unpack modules that are packed
  89. using any format it can    understand.  (This includes PowerPacker    format,    if
  90. you have the powerpacker.library installed as well.)
  91.  
  92.     You    may be skeptical about keeping a 50K program resident in memory.
  93. Never fear - thanks to a custom    memory management and overlay system,
  94. MultiPlayer uses only the memory it needs to do    its job.  All of the module
  95. players    are loaded only    when needed, and any players not currently in use
  96. are unloaded on    demand if the system runs out of memory.  The parts of the
  97. program    used to    control    MultiPlayer's various windows are also only loaded
  98. on when    they are needed    (when the windows are open) and    are freed as
  99. necessary.
  100.  
  101.     For    all you    hackers    (used in the positive meaning) that like to rip    out
  102. every form of music imaginable,    when you come across some obscure module
  103. format that nothing understands, don't despair.  There are several special
  104. formats    built into MultiPlayer that you    can use    to easily interface it to
  105. any kind of module.  All you need is the module, some player code for the
  106. module (if the module doesn't already have embedded player code), and a
  107. little assembly    language programming.  Details on all three formats are    in
  108. the separate file 'Formats.doc'.  If you are the author    of a music composer
  109. program, you should also read this document and    consider supporting the
  110. GMOD embedded-player module format in your program.
  111.  
  112.  
  113.  
  114.                    Control Panel
  115.                    ~~~~~~~~~~~~~
  116.  
  117.     The    main MultiPlayer window    normally sits quietly in the title bar.
  118. However, if you    click the zoom gadget under 2.0    or click the right mouse
  119. button under 1.3, it will become a small control panel.     Under 2.0, if
  120. you have a 3-button mouse, the middle button will act the same as the
  121. zoom gadget.  This panel displays a few    pieces of information about the
  122. module currently playing, and has some buttons you can use to control
  123. MultiPlayer.
  124.  
  125.     When running under Workbench 2.0, the MultiPlayer control panel is an
  126. AppWindow, so you can play modules by simply dropping their icons into the
  127. MultiPlayer window.  When you do, the new module (or several modules, if
  128. you extended-select them) replaces the current program,    and MultiPlayer
  129. starts playing the first module    immediately.  This works basically like
  130. selecting modules with the New button.
  131.  
  132. Module box
  133.  
  134.     This box displays the filename of the module currently loaded
  135. (essentially the same as what is displayed in the title    bar).  Any 'mod.'
  136. prefixes for Soundtracker/Noisetracker modules will not    be displayed.
  137.  
  138. Type box
  139.  
  140.     Displays the type of the loaded module (as MultiPlayer sees    it).
  141. Simple enough?
  142.  
  143. Author box
  144.  
  145.     Displays the name of the person who    wrote this module, if MultiPlayer
  146. can glean this information from    the module.  Most current module formats
  147. don't have direct facilities for identifying the author - in this case, the
  148. box will just display 'Unknown'.  Soundtracker/Noisetracker modules often
  149. have author names embedded in the instrument list - in this case,
  150. MultiPlayer will try to    make a good guess by searching for keywords such as
  151. 'by' in    the instrument list.  (If it screws up for some    reason,    you can
  152. always TYPE the    module HEX to find out for sure.) MED modules have somewhat
  153. better support,    but they still don't have a convenient 'author' field -
  154. just a catch-all 'annotation' field, which MultiPlayer processes much the
  155. same way as with Soundtracker modules.    GMOD modules are the only types    I
  156. know of    that directly support author identification, but they are at the
  157. moment few and far between.  (Let's get with it, OK?  Don't all    you
  158. wonderful musicians want to be recognized?)
  159.  
  160. Song gadget
  161.  
  162.     This gadget    serves two purposes.  First, it    displays the name of the
  163. currently loaded module    or song    as recorded in the module itself.  For
  164. example, with Soundtracker/Noisetracker    modules    this gadget will display
  165. the song name as recorded in the first 20 bytes    of the file.  Many module
  166. formats    don't have built-in name fields - in this case, the box will just
  167. display    'Unknown.'
  168.  
  169.     For    most types of modules, which support only one song per module, this
  170. gadget will serve no purpose other than    displaying the song name - clicking
  171. on it will do nothing.    However, some module formats such as (GMODs) allow
  172. several    independent songs to be    contained in a single module (for example,
  173. to save    memory by using    the same instruments on    several    songs).     In that
  174. case, this gadget will cycle through the available songs in the    module.
  175. You can    also change songs using    the left and right arrow keys.
  176.  
  177. New button
  178.  
  179.     This button    is equivalent to clicking the right mouse button while the
  180. main MultiPlayer window    is active.  It displays    the file requester and lets
  181. you select any number of modules.  The new list    of modules replaces the
  182. current    program, if there was one.  The    first module in    the list (or a
  183. random module, if you have selected random playing) will be started.  The
  184. program    will be    created    with the order in which    the modules were displayed
  185. in the file requester.    (At least this is how the current 2.0 file
  186. requester works    - it may change.)
  187.  
  188. Play button
  189.  
  190.     Starts or continues    playing    a module that was previously stopped but
  191. not unloaded.  If the module type supports the continue    feature, the module
  192. will continue playing where it left off.  Otherwise it will start again
  193. from the beginning.
  194.  
  195. Stop button
  196.  
  197.     Stops the current module without unloading it.  Audio channels and
  198. interrupts are freed while a module is stopped,    so you don't have to exit
  199. MultiPlayer completely if you want to run some other program that needs    the
  200. audio hardware.     If the    module type supports restart, you can restart it
  201. where it left off by pressing the Play button.
  202.  
  203. Eject button
  204.  
  205.     Stops and unloads the currently loaded module, and frees all memory    and
  206. other resources    that the module    was using.
  207.  
  208. Next button
  209.  
  210.     Loads and plays the    next module in the current program list.  If you
  211. have selected random play, this    button simply loads another module in the
  212. list, at random.  This is the same as pressing the down    arrow key in the
  213. MultiPlayer window.
  214.  
  215. Prev button
  216.  
  217.     Loads and plays the    previous module    in the program list.  If you have
  218. selected random    play, this button does basically the same thing    as the Next
  219. button - picks another module at random.  This button does the same thing
  220. as pressing the    up arrow key in    the MultiPlayer    window.
  221.  
  222. Program    button
  223.  
  224.     Opens the Program window, described    below.    Under 2.0, you can
  225. also do    this by    clicking the right mouse button    while the main MultiPlayer
  226. window is active.
  227.  
  228. Prefs button
  229.  
  230.     Opens MultiPlayer's Preferences window, described later.
  231.  
  232.  
  233.  
  234.                   Program Window
  235.                   ~~~~~~~~~~~~~~
  236.  
  237.     The    program    window displays    a list of all the modules in the current
  238. module 'program'. You can select modules from the list to load and play
  239. immediately.  You can also build and rearrange your program using this
  240. window.     (Under    1.3, this window provides the only way to build    programs
  241. from within MultiPlayer, since the ARP file requester doesn't support
  242. multiselect.) You get this window by pressing the 'Program' button on the
  243. main window's control panel, or by pressing the Help key in the MultiPlayer
  244. window,    or, under 2.0, by simply clicking the right mouse button while the
  245. main window is active.    Note that this window doesn't cause the main
  246. control    panel to "freeze" - you    can still watch    and use    it while this
  247. window is open.     In fact, all of MultiPlayer's windows (even the file
  248. requester) are asynchronous.
  249.  
  250.     If sequenced play is selected (the default), when one module is
  251. finished, the next lower one on    the list is loaded and played.    (This only
  252. applies    on modules that    can detect repeat - most do, but on those that
  253. don't, the module will just play forever until you explicitly tell
  254. MultiPlayer to go to the next module.) With random play, a different module
  255. will be    randomly chosen.  There    is no limit to the number of modules you
  256. can have in a program, and modules in the program can be located in many
  257. different directories -    MultiPlayer will remember the location of each
  258. module.
  259.  
  260.     When running under Workbench 2.0, the Program window is an AppWindow,
  261. so you can add modules by simply dropping their    icons into this    window.
  262. This window works slightly differently from the    main Multiplayer window,
  263. however.  When you drop    icons into this    window,    the behavior is    the same as
  264. if you had selected the    modules    with the 'Add' button:    The new    modules    are
  265. added to the end of the    current    program    list, and whatever is currently
  266. playing    remains    unaffected.
  267.  
  268.     Besides the    module listing,    this window contains several buttons that
  269. allow you to manipulate    the module list.  These    are described below:
  270.  
  271. Top, Up, Down, and Bot buttons
  272.  
  273.     These buttons allow    you to rearrange the modules in    the program.  They
  274. work on    the currently selected (probably currently playing) module, and
  275. their meanings should be obvious.
  276.  
  277. Add button
  278.  
  279.     This button    works basically    the same way as    the 'New' button on the
  280. main window - it brings    up the file requester and allows you to    select
  281. modules.  However, it doesn't cause the previous program to be cleared when
  282. you finish, and    it doesn't start playing a new module immediately.  Under
  283. 1.3, you'll have to use this button to repeatedly bring up the file
  284. requester in order to build programs.  However,    with the registered version
  285. of MultiPlayer you only    have to    build a    program    once, save it, then tell
  286. MultiPlayer to reload it whenever it starts up.     (Hint,    hint...)
  287.  
  288. Del button
  289.  
  290.     This button    deletes    the currently selected module in the program list.
  291. If this    module is currently playing, the module    continues playing - it only
  292. removes    the module from    the program, not immediately from memory.
  293.  
  294. Clear button
  295.  
  296.     Clears the entire current program list.  As    with the 'Del' button, it
  297. does not stop any currently playing module.
  298.  
  299. Sort button
  300.  
  301.     Sorts the entire current program list alphabetically.  Handy if you
  302. like to    use random play    (and thus don't really care about the play order)
  303. but you'd like a nice neat module listing.
  304.  
  305. Load button
  306.  
  307.     Brings up the file requester so you    can load a previously saved program
  308. from disk.  (This button will only work    on the registered version of
  309. MultiPlayer.) The newly    loaded program will replace the    current    program.
  310.  
  311.     Note that you can also load    saved programs from the    regular    module
  312. requester - programs are recognized just like modules, and programs
  313. selected this way will automatically be    loaded and run.     (You could even
  314. put the    name of    another    program    file at    the bottom of the first    one, and
  315. chain programs together!)
  316.  
  317. Save button
  318.  
  319.     Brings up the file requester and lets you save the current program to a
  320. disk file.  (Also only works on    the registered version.) You can then load
  321. it again later through the Load    gadget or using    any method normally used to
  322. select modules - the file requester, Workbench extended-select when
  323. starting MultiPlayer, or CLI arguments.     (See the 'Startup' for    details    on
  324. starting MultiPlayer.)
  325.  
  326.     If you want    to create or modify module program files yourself, just
  327. take a look at one of the files    MultiPlayer generates -    it's just a simple
  328. text file.  Lines starting with    'DIR' denote changes of    directory - all
  329. filenames after    that until another 'DIR' keyword will be looked    for in that
  330. directory.
  331.  
  332.  
  333.  
  334.                 Preferences    Window
  335.                 ~~~~~~~~~~~~~~~~~~
  336.  
  337.     MultiPlayer's built-in Preferences window can be opened by clicking on
  338. the 'Prefs' button in the main MultiPlayer window.  It contains    a few
  339. options    (there will be more in future versions)    which you can use to tailor
  340. MultiPlayer to your own    preferences.  The gadgets are described    below:
  341.  
  342. Play gadget
  343.  
  344.     Use    this to    select between sequenced play, random play, and    'over and
  345. over' mode.  In sequenced play, the modules in the program list are played
  346. one after another, from    beginning to end, in the order they appear in the
  347. program    list.  In random play, a module    plays once and then another is
  348. randomly selected.  In 'once' mode, the    song is    played only once, then is
  349. unloaded and MultiPlayer becomes idle.    In 'over and over' mode, anything
  350. you select is played forever until you tell MultiPlayer    to start a
  351. different module.  (In these last two mode, you    can still use the 'Next'
  352. and 'Prev' buttons in the main window to change    modules; MultiPlayer just
  353. doesn't do it by itself.)
  354.  
  355. Show gadget
  356.  
  357.     This cycle gadget allows you to select the type of display you want    to
  358. appear in the main window's title bar while a module is playing.  In clock
  359. mode, a    clock appears displaying the amount of time this module    has been
  360. playing    in minutes and seconds.     In sequence mode (this    has no relation    to
  361. the sequence mode in the 'Play'    gadget), on NoiseTracker or similar
  362. modules    that play sequences of blocks, the current sequence number and the
  363. number of sequences in the song    is displayed.  (On modules that    don't
  364. support    this, the clock    is displayed.) You can tell MultiPlayer    to display
  365. the current sequence number either starting from 0 and ending at length-1,
  366. as most    trackers display sequence numbers, or starting from 1 and ending
  367. at (length), which is the more 'natural' way of    counting.  Selecting the
  368. 'Nothing' option in this gadget    will leave you with a simple, clean,
  369. unadulterated title bar.
  370.  
  371. Save button
  372.  
  373.     Saves the current preferences to the disk file ENV:MultiPlayerPrefs, as
  374. well as    to the same file in ENVARC:.  (With a preferences window as simple
  375. as this, there's no real need for separate 'Save' and 'Save Default'
  376. options.)
  377.  
  378.     The    preferences saved include, as well as the current settings of the
  379. above two gadgets, the positions of the    three main MultiPlayer windows.    The
  380. next time you run MultiPlayer, the windows will    pop up wherever    they were
  381. when you saved the preferences.     Note that the position    of the main control
  382. panel window can only be updated if the    window is currently in the "zoomed"
  383. state when you save the    preferences, so    you can    see the    module information
  384. and gadgets.  (This is due to a    slight deficiency in 2.0.)
  385.  
  386. OK button
  387.  
  388.     Does exactly the same thing    as the close gadget on the window does -
  389. closes the Preferences window.    It does    NOT cause the new preferences to be
  390. activated, because they    are activated the moment you select them.  (Isn't
  391. multitasking wonderful?) There is no 'Cancel' gadget because I figure it's
  392. not too    difficult to change back any buttons you accidentally hit, since
  393. there are so few...
  394.  
  395.  
  396.  
  397.                 Keyboard Shortcuts
  398.                 ~~~~~~~~~~~~~~~~~~
  399.  
  400.     Several keyboard shortcuts are available from any MultiPlayer window
  401. (except    the file requester).  Most of these have been mentioned    before in
  402. this document, but they    are listed all together    here.  All of these are
  403. available under    1.3 as well as 2.0.  These keys    are listed below:
  404.  
  405. ESC key
  406.  
  407.     Terminates MultiPlayer immediately (a shortcut for the close gadget    on
  408. the main window.
  409.  
  410. F1 key
  411. Help key
  412.  
  413.     Opens the Program window, or closes    it if it is already open.
  414.  
  415. F2 key
  416.  
  417.     Opens the Preferences window, or closes it if it is    already    open.
  418.  
  419. Help key
  420.  
  421.     Under 2.0, brings up the module program window (a shortcut for the
  422. 'Program' button on the    main window).
  423.  
  424. Spacebar
  425.  
  426.     If a module    is currently playing, stops (or    pauses it) without
  427. unloading, like    the 'Stop' button in the main window.  If a module is
  428. loaded but NOT playing,    it continues or    restarts it, just like the 'Play'
  429. button.
  430.  
  431. Delete key
  432.  
  433.     Unloads ('ejects') the currently loaded module.
  434.  
  435. Up/down    arrows
  436.  
  437.     These switch to the    previous or next modules in the    program    list,
  438. respectively.  In random play, these simply select another module at
  439. random.     (These    are shortcuts for the 'Next' and 'Prev'    buttons    in the main
  440. window.)
  441.  
  442. Left/right arrows
  443.  
  444.     For    modules    that contain more than one song, these select the previous
  445. or next    song, respectively (shortcuts for the 'Song' cycle gadget).
  446.  
  447.  
  448.  
  449.                   Startup Options
  450.                   ~~~~~~~~~~~~~~~
  451.  
  452.     When starting MultiPlayer from Workbench (either 1.3 or 2.0), you can
  453. extended-select    the icons of as    many modules as    you want when you start
  454. MultiPlayer.  It will add all of these modules to the program and
  455. immediately start playing the first one    (or a random selection,    if you have
  456. selected random    play in    your saved preferences).
  457.  
  458.     If you're running Kickstart 1.3, MultiPlayer will accept a single
  459. argument from the CLI (don't use quotes, even if there are spaces).  If
  460. this argument ends in a    ':' or '/', MultiPlayer    will change to that
  461. directory before displaying the    ARP file requester.  If    it doesn't end in
  462. one of these characters, MultiPlayer will try to load the specified file as
  463. a module and start it playing rather than displaying the file requester
  464. immediately.
  465.  
  466.     If you're running Kickstart 2.0, MultiPlayer supports some extra
  467. command-line options:
  468.  
  469.     DIR=DIRECTORY,MODULES/M,SCREEN/K,NOREQUEST/S,NOWINDOW/S,NOREXX/S
  470.  
  471.     (On    the unregistered version, the NOREXX option will not appear.)
  472. Following is a description of these arguments:
  473.  
  474. DIRECTORY
  475.  
  476.     The    first argument on the command line (or any argument preceded by
  477. this keyword) tells MultiPlayer    what directory to go to    the first time it
  478. displays the file requester.  This is also where it will look for modules
  479. you specify on the command line    (see below) if you don't specify full
  480. pathnames for them.
  481.  
  482. MODULES/M
  483.  
  484.     The    second argument    (if you    don't explicitly use the DIRECTORY or
  485. MODULES    keywords) begins a list    of modules to put into MultiPlayer's
  486. program    list on    startup.  MultiPlayer imposes no limitations on    the number
  487. of modules you can specify using this keyword, although    command    lines are
  488. limited    to 256 characters.  After MultiPlayer starts up, instead of showing
  489. the file requester immediately,    it will    load and begin playing the first
  490. module in the program list (or a randomly selected module, if you have
  491. selected random    playing).  With    the registered version of MultiPlayer, you
  492. can specify a program file to load and start initially instead of a list of
  493. modules.
  494.  
  495. SCREEN/K
  496.  
  497.     You    can use    this parameter to tell MultiPlayer to open its windows on a
  498. screen other than the Workbench    (or default) screen.  Just supply the name
  499. of the public screen as    this parameter,    and MultiPlayer    will try to use    it
  500. for all    its windows.  The named    public screen must already be open.
  501.  
  502. NOREQUEST/S
  503.  
  504.     If you specify the switch, MultiPlayer will    not display the    file
  505. requester immediately after it loads, even if you don't specify any modules
  506. to start playing.  If you don't specify any modules, MultiPlayer will
  507. simply sit idle    until you tell it to do    something.
  508.  
  509. NOWINDOW/S
  510.  
  511.     This switch    causes MultiPlayer to load and run without a window.  If
  512. you specify modules to start playing, MultiPlayer will play them as usual,
  513. but you    won't see any visual indication that MultiPlayer is running.  You
  514. can still control the registered version of MultiPlayer    through    its ARexx
  515. port, assuming you haven't turned that off as well.  Using this switch will
  516. save about 5K of memory, since the part    of MultiPlayer that handles the
  517. window interface is never loaded (and of course    the window itself is not
  518. occupying memory).
  519.  
  520. NOREXX/S
  521.  
  522.     If you specify this    switch (which only exists on the registered
  523. version), MultiPlayer will not open its    ARexx port.  Using this    switch will
  524. save a little extra memory (not    much though - less than    1K) if you don't
  525. need the ARexx port.
  526.  
  527.     If you specify both    NOREXX and NOWINDOW, you will effectively have no
  528. way to control MultiPlayer apart from rebooting    - it will go on    playing
  529. modules    as you instruct    it to at first,    and will not stop unless it
  530. encounters a major error of some kind.    (If that happens, you basically
  531. "lose" it for good.) I don't recommend doing this without a good reason.
  532.  
  533.  
  534.  
  535.                 ARexx Port
  536.                 ~~~~~~~~~~
  537.  
  538.     If you have    ARexx, either as an independent    program    in 1.3 or as part
  539. of the operating system    in 2.0+, you can use it    to control the registered
  540. version    of MultiPlayer.     Whenever MultiPlayer is running, there    is an ARexx
  541. port available called "RXTRACKER" which    you can    send various commands to.
  542. MultiPlayer's ARexx port is designed to be (mostly) compatible with the
  543. program    RxTracker by Dominic Giampaolo.     In addition, it has several
  544. extended features, and of course you can use it    to play    all the    different
  545. kinds of modules MultiPlayer understands.
  546.  
  547.     If MultiPlayer runs    into an    error when trying to load or play a module,
  548. it generally returns an    error code of 10.  When    any error occurs, a pointer
  549. to a descriptive error string is saved and you can get it with the
  550. LASTERROR command to display for the user.
  551.  
  552.     A listing of the ARexx commands MultiPlayer    understands follows:
  553.  
  554. LOAD    <filename>
  555.  
  556.     Loads a module into    memory from disk.  It is generally a good idea to
  557. supply a complete pathname, since MultiPlayer looks for    the module starting
  558. at whatever directory the file requester last happened to be looking at.
  559. This command does not start the    module playing.     If you    want to    start
  560. playing    immediately, you don't have to use this command at all - you can
  561. simply supply a    filename on the    PLAY command and it will load and start
  562. playing    immediately.  Note that    unless you tell    MultiPlayer to load a
  563. program    file, this command won't affect the program list at all - the ARexx
  564. port in    general    operates independently of the standard user interface.    If
  565. you explicitly tell MultiPlayer    to load    a program file using this command,
  566. then the new program list will replace the old one.
  567.  
  568. PLAY    [<filename>] [<songnumber>]
  569.  
  570.     Starts playing a module.  If you supply the    filename, MultiPlayer stops
  571. any module currently playing and tries to load the specified module from
  572. disk, like the LOAD command.  If you don't supply the filename, MultiPlayer
  573. plays (or re-plays from    the start) an already-loaded module.  (If no module
  574. is loaded and you don't specify a filename, MultiPlayer returns error code
  575. 5 and otherwise    does nothing.) For modules with    more than one song, you    can
  576. supply the song    number to play.     Songs are numbered starting at    zero.  If
  577. you don't supply a song number, the first one (song zero) is assumed.
  578.  
  579. STOP
  580.  
  581.     Stops playing any module that is currently playing without unloading
  582. the module.  You can then restart it later with    PLAY or    CONTINUE.
  583.  
  584. UNLOAD
  585.  
  586.     Stops and unloads any currently loaded module.
  587.  
  588. CONTINUE
  589.  
  590.     Tries to restart a stopped module at the position it was at    before the
  591. STOP command was given.     If the    module has never been started, it simply
  592. starts from the    beginning.  If the module was already playing, it does
  593. nothing.  If the module    type doesn't support restarting, MultiPlayer
  594. returns    error code 5 and does NOT start    the module - you can then use PLAY
  595. to start again from the    beginning if you want, or else chew out    the user
  596. for using weird    module formats.
  597.  
  598. OPENWINDOW
  599.  
  600.     Opens the main MultiPlayer window.    It will    be opened in the small
  601. title-bar zoom state, and none of MultiPlayer's other windows will be
  602. opened with it.     If the    window was already open, this command does nothing.
  603. It returns an error if the window can't be opened.  Remember that while the
  604. window is open the user    can use    it to change modules and such, possibly
  605. messing    up your    perfectly organized and    timed ARexx-controlled playing
  606. sequences.
  607.  
  608. CLOSEWINDOW
  609.  
  610.     Closes the MultiPlayer window, if it was open.  MultiPlayer    remains
  611. active,    but impervious to user interface (through Intuition anyway).  Now
  612. only ARexx commands can    affect MultiPlayer.
  613.  
  614. LASTERROR
  615.  
  616.     Returns an error message describing    the last error that occurred that
  617. had to do with the ARexx port.    (Errors    that the user causes by
  618. manipulating the window    do not affect this.) You'll have to have 'options
  619. results' turned on for this to work, and the error will appear in the
  620. 'RESULT' variable.
  621.  
  622. QUIT
  623.  
  624.     Causes MultiPlayer to terminate immediately.
  625.  
  626.  
  627.  
  628.                  Messages
  629.                  ~~~~~~~~
  630.  
  631.     This section lists most of the error or warning messages MultiPlayer
  632. can produce.  Look here    if you have trouble deciphering    the meaning of one.
  633.  
  634. "Not enough chip memory"
  635.  
  636.     Tracker-style modules generally must be loaded into    one big    continuous
  637. chunk of chip memory.  Therefore, even if the Workbench    (or some other
  638. program) says you have enough memory, it may not have one big enough chunk.
  639. Close some windows, exit some programs.     If all    else fails, reboot and try
  640. fresh.
  641.  
  642. "Not enough memory"
  643.  
  644.     You    really are getting low.     MultiPlayer doesn't normally need too much
  645. non-chip memory, since modules are always loaded into chip memory.  If you
  646. get this message, it means you don't have much memory of ANY kind
  647. available.  Better free    up something quick.
  648.  
  649. "Required memory occupied"
  650.  
  651.     You    will only get this message from    non-relocatable    AMOD or    GMOD
  652. modules.  It means that    the module has a specific address it must be loaded
  653. into, but part or all of the required block of memory is already in use.
  654. Free up    as much    memory as possible and try again.  If most of your memory
  655. is free    and you    still can't load it, chances are there's some little
  656. allocated fragment that    some program has forgotten about that's still
  657. sitting    in the required    area.  Your best bet is    to reboot and try on a
  658. fresh system.  If you have more    than 512K of chip memory, try running my
  659. program    'ChipMunch' (included with MultiPlayer)    just after you reboot to
  660. keep programs out of the commonly used areas.
  661.  
  662. "Nothing selected"
  663.  
  664.     Not    an error, this simply means that you pressed Cancel in the file
  665. requester without selecting any    modules.  MultiPlayer then happily goes    on
  666. doing whatever it was already doing.
  667.  
  668. "Unknown module type"
  669.  
  670.     MultiPlayer    doesn't recognize the file you selected as one of the
  671. module types it    knows.    Either this isn't a music module, or it's one that
  672. it doesn't know how to handle.  If it is a music module that MultiPlayer
  673. doesn't know about, send me the module and player/interface code, and it
  674. should make it into the    next version of    MultiPlayer.
  675.  
  676. "Corrupt module"
  677.  
  678.     MultiPlayer    recognized the module, but it didn't look right for some
  679. reason.     Maybe it's a module written with an incompatible version of the
  680. music program, or maybe    the module itself got munched somehow.
  681.  
  682. "Error playing module"
  683.  
  684.     A general catch-all.  This error usually is    displayed as a result of
  685. error reports from initialization routines of individual players.  It
  686. generally means    that the module    loaded fine, but the player had    trouble
  687. playing    it.  Sometimes it means    the same thing as "Corrupt module", or it
  688. might mean that    the player ran out of memory but was too stupid    to tell
  689. MultiPlayer about it specifically.
  690.  
  691. "Can't load module"
  692.  
  693.     The    requested file was not found, or there was a disk error    while
  694. reading    it.  If    you get    this message after selecting a file from the file
  695. requester, chances are the disk    is corrupt (in this case AmigaDOS should
  696. have already given you a requester saying so), or the file may be open for
  697. writing    from some other    program.
  698.  
  699. "Directory not found"
  700.  
  701.     Somehow you    managed    to tell    MultiPlayer to load something from a
  702. directory that doesn't exist.  Maybe you moved the directory somewhere
  703. else, or forgot    an Assign somewhere.  This usually only    happens    with ARexx
  704. commands or loaded program lists.
  705.  
  706. "Audio hardware in use"
  707.  
  708.     MultiPlayer    can't allocate the audio hardware through the audio.device.
  709. This probably means that some other music editor or player is currently
  710. running.  Find the culprit program and close it.  If all else fails, reboot
  711. and try    again.
  712.  
  713. "No CIAB timers available"
  714.  
  715.     MultiPlayer    generally uses one of the two timers on    CIA (Complex
  716. Interface Adapter) B for timing    its music.  However, other programs like to
  717. use these also.     In particular,    (I believe) one    of the timers may be in    use
  718. if the serial port is in operation.  Other than    that, music programs are
  719. generally the biggest consumers    of CIAB    timers.     Make sure no other music
  720. player or composer programs are    running, and try closing terminal programs
  721. or other programs that use the serial port.
  722.  
  723. "Please decompress this module"
  724.  
  725.     It is unlikely that    you will ever get this message,    but if you do, it
  726. means that (a) the module MultiPlayer is trying    to load    is compressed
  727. somehow    (MultiPlayer had to use    the xpkmaster.library to decompress it),
  728. and (b)    it is an AMOD or GMOD module that must load at an absolute address,
  729. and (c)    MultiPlayer would have to re-load the module rather than just
  730. copying    it to its final    position because the memory the    module occupied
  731. initally overlapped the    required module    address.  If you don't quite
  732. follow,    don't sweat - just decompress the module.
  733.  
  734.  
  735.  
  736.                  Supported Formats
  737.                  ~~~~~~~~~~~~~~~~~
  738.  
  739. MultiPlayer currently supports the following module types:
  740.  
  741.     15-instrument SoundTracker modules (most anyway)
  742.     31-instrument SoundTracker V2.3-2.5/NoiseTracker V1.0-1.3D modules
  743.  
  744.     NoiseTracker 1.3D packed modules (with or without the embedded player)
  745.  
  746.     StarTrekker 1.2    AM/FM modules (Extra '.NT' file    required)
  747.  
  748.     MED 3.xx modules (MMD0 modules only - not "Song&Samples" files)
  749.         (no 2.xx modules anymore - use MED 3.xx    to convert them!)
  750.  
  751.     SoundFX    V1.3 executable    modules    (Player    V2.2)
  752.         (Will probably ONLY work with this version, since it does
  753.         some run-time patching to get it to play under MultiPlayer.)
  754.  
  755.     Old Future Composer 'SMOD' modules (what version is this specifically???)
  756.     Future Composer    1.4 ('FC14') modules
  757.  
  758.     JamCrackerPro 1.0a modules
  759.  
  760.     SoundMonitor 2.0 modules
  761.  
  762.     Dave Whittaker modules
  763.         (Be careful - these aren't completely system friendly...)
  764.  
  765.     Delta Music modules (two versions)
  766.  
  767.     Oktalyzer V1.1 4-channel modules (untested)
  768.  
  769.     SidMon modules (untested)
  770.  
  771.     Mark II    modules    (untested)
  772.  
  773.     Generic    embedded-player    modules    that start with    something like
  774.             jmp init(pc)
  775.             jmp music(pc)
  776.             jmp end(pc)
  777.         (Such as NoiseTracker 1.3 packed w/player modules)
  778.  
  779.     AudioMaster III    sequenced 8SVX sounds (mono only)
  780.  
  781.     'XMOD',    'AMOD',    and 'GMOD' formats described in    'Formats.doc'
  782.  
  783.     Some of the    module types are marked    as 'untested'.    This means exactly
  784. what it    says - I found out the appropriate methods to play these and easily
  785. added support into MultiPlayer,    but I didn't have any modules to test it
  786. on.  So    if I made a stupid mistake, one    or more    of these may not work at
  787. all.  If you try one of    these formats and it doesn't work, send me a few
  788. modules    in the appropriate format to test with,    and if you're the first to
  789. do so, I'll register you for free and send you the new bug-fixed version of
  790. MultiPlayer.
  791.  
  792.     Although sequenced 8SVX sounds are technically only    sampled    sound
  793. files, they have some music capability and look    promising.  Besides, the
  794. player also plays non-sequenced    8SVX sounds, so    you can    also play your
  795. movie clips and    such with MultiPlayer.    (I'm not sure if AudioMaster III is
  796. the only program that currently    supports sequenced 8SVX    files, but it's the
  797. only one I've seen so far.) Stereo is currently not supported - sorry, I'll
  798. get to that eventually.
  799.  
  800.  
  801.  
  802.                   History
  803.                   ~~~~~~~
  804.  
  805. 1.11a    (12-Dec-91)
  806.     Fixed bug in 8SVX player.
  807.     Window positions are now saved with preferences.
  808.  
  809. 1.11    (10-Dec-91)
  810.     Repeat detection bug in    ST/NT player fixed.
  811.     Program    and preferences    windows    now save their positions while closed.
  812.     Enhanced author    name detection.
  813.     Added middle-mouse-button zoom feature.
  814.     Added 'Nothing'    option to the show mode    in preferences.
  815.     Improved Delta Music module recognition.
  816.  
  817. 1.10    (18-Nov-91)
  818.     Right mouse button in the main window has changed functions:
  819.         Under 1.3, it zooms the    window (since there's no zoom gadget)
  820.         Under 2.0, it shows the    program    window (like the Help or F1 key)
  821.     File requester is now asynchronous (other windows remain active).
  822.     Control    panels are now fully 1.3 compatible.
  823.         (Although they still don't look as nice as in 2.0...)
  824.     Keyboard shortcuts now supported in all    control    panels.
  825.     Added public screen support.
  826.     Added "play once" feature.
  827.     DMA delays now use scanline waits instead of delay loops.
  828.     Re-opening sub windows now closes them rather than bringing them to the    front.
  829.     Added AppWindow    support    for 2.0.
  830.  
  831. 1.01    (8-Nov-91)
  832.     Added 'Sort' button in program window.
  833.     Fixed a    serious    bug in GMOD player.  (Only serious if you have GMOD modules...)
  834.     Enhanced author    name recognition for ST/NT modules.
  835.  
  836. 1.00    (5-Nov-91)
  837.     This is    basically a rewrite of most of the program.
  838.         (I'm not listing all the additions - there are way too many.)
  839.     Major changes and additions to Formats.doc.
  840.     Music no longer    cuts off when file requester is    displayed.
  841.     Removed    built-in code compression.  (Maybe I'll put it back in later.)
  842.     Audio device now allocated while playing music.
  843.     Fixed SoundFX player bug which caused crashing on advanced processors.
  844.     Players    now use    longer DMA delays (normally 300) only on fast processors.
  845.         (Wouldn't want to bog down you poor ol'    68000 users would we?)
  846.     Major rewrite of player    selection code.
  847.     CIAB interrupts    now defer to software interrupts to avoid hogging
  848.         CPU time in a high-priority interrupt.
  849.  
  850. 0.95A    (6-Sep-91)
  851.     Fixed bug where    song position appeared when no module was playing.
  852.     Fixed ST/NT player bug for modules with    negative song repeat positions.
  853.  
  854. 0.95    (27-Jul-91)
  855.     Added song position indicator for ST/NT    and MED    modules.
  856.     Added code to turn low-pass filter off by default (will    soon be    selectable).
  857.     Added Messages section to the documentation.
  858.     Fixed window position so it snuggles right up next to the screen gadgets.
  859.  
  860. 0.94A    (26-Jul-91)
  861.     Fixed player window height on pre-2.0 operating    systems.
  862.     Increased delay    loop (ugh!) in NoiseTracker player for faster processors.
  863.     Fixed song repeat bug in NoiseTracker player.
  864.     Hacked NoiseTracker player to play old 15-instrument modules.
  865.     Fixed memory trashing bug in NoiseTracker player.
  866.         (I hate    cleaning up someone else's code!)
  867.  
  868. 0.94    (23-Jul-91)
  869.     Uses one of the    CIAB timers for    timing rather than the VBlank interrupt.
  870.     Finally    uses Workbench 2.0 ASL file requester if available.
  871.     Added MED 3.xx modules,    removed    MED 2.xx songs.
  872.  
  873. 0.93    (3-Jul-91)
  874.     Workbench 2.0 compatible (although some    modules    may not    be).
  875.  
  876. 0.92    (7-Jun-91)
  877.     Added 'AMOD' absolute loading module format described in 'Formats.doc'.
  878.     Added 'GMOD' general module format described in    'Formats.doc'.
  879.     Added NoiseTracker 1.3D    packed (with player) modules.
  880.     Added StarTrekker 1.2 AM synthesized modules.
  881.     Updated    the SoundTracker/NoiseTracker player.
  882.         (New player comes from NoiseTracker 1.3D)
  883.  
  884. 0.91    (29-Apr-91)
  885.     Added 'XMOD' format described in 'Formats.doc'.
  886.     Removed    "unknown" module formats (turned those modules into XMOD's)
  887.  
  888. 0.90    (27-Apr-91)
  889.     First preliminary release.  Nothing fantastic.
  890.  
  891.  
  892.  
  893.                    Registration
  894.                    ~~~~~~~~~~~~
  895.  
  896.     MultiPlayer    is Shareware.  Although    I detest the fact that humans must
  897. prove their worth to society through a meaningless medium known    as money,
  898. today's society requires it - without money you don't eat, and you don't
  899. buy Amigas. Therefore, for $15 or more you will    get the    registered version
  900. of MultiPlayer which allows loading and    saving of programs (module lists),
  901. as well    as the full-featured ARexx port    described later    in this    document
  902. (useful    for playing modules with AmigaVision and the like).  Of    course,    you
  903. also gain my favor - suggestions for improvements will be taken    much more
  904. seriously from registered users.
  905.  
  906.     I'm planning to release the source code to MultiPlayer.  However, it
  907. uses many of my    library    routines that I    have not released yet (though I'm
  908. planning to when I have    the chance), so    it will    have to    wait a while. The
  909. source code will probably be available with a $30 registration fee (or an
  910. additional $15 for users who have already paid the $15 registration fee).
  911. How hard I work    on getting my library routines cleaned up and released,    and
  912. therefore how soon I get MultiPlayer's source code released, depends a
  913. great deal on how much support I get for MultiPlayer.
  914.  
  915.  
  916.  
  917.                   Contact Address
  918.                   ~~~~~~~~~~~~~~~
  919.  
  920.     I tend to move around a great deal,    so mail    sent directly to me
  921. sometimes has a    hard time catching up.    If you want mail to reach me (it
  922. may take a while, but it WILL reach me), send it to this address:
  923.  
  924.     Bryan Ford
  925.     8749 Alta Hills    Circle
  926.     Sandy, UT 84093
  927.  
  928.     I can be reached more quickly (for the time    being anyway) on the phone
  929. or through one of the electronic mail addresses    below:
  930.  
  931.     (801) 585-4619
  932.     bryan.ford@m.cc.utah.edu
  933.     baf0863@cc.utah.edu
  934.     baf0863@utahcca.bitnet
  935.  
  936.     If you want    to get something to me through the mail    more quickly, FIRST
  937. call or    E-mail me to make sure I'm still here, then send it to this
  938. address:
  939.  
  940.     Bryan Ford
  941.     27104 Ballif Hall
  942.     University of Utah
  943.     Salt Lake City,    UT 84112
  944.  
  945.  
  946.